home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / terminal_colour < prev    next >
Text File  |  2001-05-25  |  3KB  |  87 lines
  1. SYNOPSIS
  2.         varargs string terminal_colour( string str
  3.                                       , null|mapping|closure map
  4.                                       , int wrap, int indent )
  5.  
  6. DESCRIPTION
  7.         If <map> is given as a non-0 value, this efun expands all
  8.         colour-defines of the form "%^KEY%^" from the
  9.         input-string and replaces them by the apropriate values found
  10.         for the color-key specified by <map>.
  11.         
  12.         If <map> is a mapping, the entries queries have the
  13.         format "KEY" : "value", non-string contents are ignored with one
  14.         exception: if the mapping contains an entry 0:value, it is used
  15.         for all otherwise unrecognized keys. The value in this case can be
  16.         a string, or a closure. If it is a closure, it takes the key as
  17.         argument and has to return the replacement string.
  18.  
  19.         If <map> is given as a closure, it is called with the KEYs to
  20.         replace, and has to return the replacement string.
  21.  
  22.         The special key "%^%^" is always replaced with the literal "%^".
  23.  
  24.         The parameters wrap and indent are both optional, if only wrap is
  25.         given then the str will be linewrapped at the column given with
  26.         wrap. If indent is given too, then all wrapped lines will be
  27.         indented with the number of blanks specified with indent.
  28.  
  29.         The wrapper itself ignores the length of the color macros and that
  30.         what they contain, it wraps the string based on the length of the
  31.         other chars inside. Therefore it is color-aware.
  32.  
  33.  
  34.         If <map> is given as 0, the efun does no colour-define detection
  35.         and replacement at all, but still does linewrapping and indentation
  36.         if requested. This way terminal_colour() doubles as a simple
  37.         line wrapping function, replacing the functionality formerly
  38.         served by sprintf("%-=s").
  39.  
  40.  
  41. EXAMPLES
  42.         mapping trans;
  43.         string str;
  44.  
  45.         trans = ([ "GREEN" : "ansi-green", "RED" : "", "BLUE" : 1 ]);
  46.  
  47.         str = terminal_colour( "%^GREEN%^ and %^RED%^ and %^BLUE%^", trans );
  48.  
  49.         This will result in str == "ansi-green and  and BLUE"
  50.  
  51.         %^GREEN%^ is expanded to ansi-green because trans defines that,
  52.         %^RED%^ is stripped because trans defines that as "" and
  53.         %^BLUE%^ gets the %^'s removed because the contents of trans are
  54.         not valid (i.e. no string). The same would happen to %^DEFINES%^
  55.         where the key is not found inside the trans mapping.
  56.  
  57.         Caveat: to replace adjacent keys, use the efun like this:
  58.  
  59.             str = terminal_colour( "%^GREEN%^%^RED%^", trans );
  60.  
  61.         A command like
  62.  
  63.             str = terminal_colour( "%^GREEN%^RED%^", trans );
  64.  
  65.         will return the logical but sometimes unexpected "ansi-greenRED".
  66.  
  67.  
  68.         Some words about wrapping:
  69.  
  70.         a string wrapped without indent would look like this:
  71.  
  72.             "this is the first line\nand this is the second line"
  73.  
  74.         a string wrapped with indent 3 would look like:
  75.         
  76.             "this is the first line\n   and this is the indented second one"
  77.  
  78. HISTORY
  79.         Efun idea and initial implementation taken from MudOS; the key
  80.         recognition strategy (including pure wrapping mode) was straightened
  81.         out in LDMud 3.2.8.
  82.         LDMud 3.2.9 added the use of closures to specify the colour mappings.
  83.         
  84. SEE ALSO
  85.         sprintf(E)
  86.  
  87.